<a href='http://github.com/angular/angular.js/edit/master/docs/content/guide/forms.ngdoc' class='improve-docs btn btn-primary'><i class="glyphicon glyphicon-edit">&nbsp;</i>Improve this doc</a>


<p>Controls (<code>input</code>, <code>select</code>, <code>textarea</code>) are ways for a user to enter data.
A Form is a collection of controls for the purpose of grouping related controls together.</p>
<p>Form and controls provide validation services, so that the user can be notified of invalid input.
This provides a better user experience, because the user gets instant feedback on how to correct the error.
Keep in mind that while client-side validation plays an important role in providing good user experience, it can easily be circumvented and thus can not be trusted.
Server-side validation is still necessary for a secure application.</p>
<h1 id="simple-form">Simple form</h1>
<p>The key directive in understanding two-way data-binding is <a href="api/ng/directive/ngModel">ngModel</a>.
The <code>ngModel</code> directive provides the two-way data-binding by synchronizing the model to the view, as well as view to the model.
In addition it provides an <a href="api/ng/type/ngModel.NgModelController">API</a> for other directives to augment its behavior.</p>
<p>

<div>
  <a ng-click="openPlunkr('examples/example-example96')" class="btn pull-right">
    <i class="glyphicon glyphicon-edit">&nbsp;</i>
    Edit in Plunker</a>
  <div class="runnable-example"
      path="examples/example-example96"
      module="formExample">

   
    <div class="runnable-example-file" 
      name="index.html"
      language="html"
      type="html">
      <pre><code>&lt;div ng-controller=&quot;ExampleController&quot;&gt;&#10;  &lt;form novalidate class=&quot;simple-form&quot;&gt;&#10;    Name: &lt;input type=&quot;text&quot; ng-model=&quot;user.name&quot; /&gt;&lt;br /&gt;&#10;    E-mail: &lt;input type=&quot;email&quot; ng-model=&quot;user.email&quot; /&gt;&lt;br /&gt;&#10;    Gender: &lt;input type=&quot;radio&quot; ng-model=&quot;user.gender&quot; value=&quot;male&quot; /&gt;male&#10;    &lt;input type=&quot;radio&quot; ng-model=&quot;user.gender&quot; value=&quot;female&quot; /&gt;female&lt;br /&gt;&#10;    &lt;button ng-click=&quot;reset()&quot;&gt;RESET&lt;/button&gt;&#10;    &lt;button ng-click=&quot;update(user)&quot;&gt;SAVE&lt;/button&gt;&#10;  &lt;/form&gt;&#10;  &lt;pre&gt;form = {{user | json}}&lt;/pre&gt;&#10;  &lt;pre&gt;master = {{master | json}}&lt;/pre&gt;&#10;&lt;/div&gt;&#10;&#10;&lt;script&gt;&#10;  angular.module(&#39;formExample&#39;, [])&#10;    .controller(&#39;ExampleController&#39;, [&#39;$scope&#39;, function($scope) {&#10;      $scope.master = {};&#10;&#10;      $scope.update = function(user) {&#10;        $scope.master = angular.copy(user);&#10;      };&#10;&#10;      $scope.reset = function() {&#10;        $scope.user = angular.copy($scope.master);&#10;      };&#10;&#10;      $scope.reset();&#10;    }]);&#10;&lt;/script&gt;</code></pre>
    </div>
  

    <iframe class="runnable-example-frame" src="examples/example-example96/index.html" name="example-example96"></iframe>
  </div>
</div>

</p>
<p>Note that <code>novalidate</code> is used to disable browser&#39;s native form validation.</p>
<h1 id="using-css-classes">Using CSS classes</h1>
<p>To allow styling of form as well as controls, <code>ngModel</code>  adds these CSS classes:</p>
<ul>
<li><code>ng-valid</code></li>
<li><code>ng-invalid</code></li>
<li><code>ng-pristine</code></li>
<li><code>ng-dirty</code></li>
</ul>
<p>The following example uses the CSS to display validity of each form control.
In the example both <code>user.name</code> and <code>user.email</code> are required, but are rendered with red background only when they are dirty.
This ensures that the user is not distracted with an error until after interacting with the control, and failing to satisfy its validity.</p>
<p>

<div>
  <a ng-click="openPlunkr('examples/example-example97')" class="btn pull-right">
    <i class="glyphicon glyphicon-edit">&nbsp;</i>
    Edit in Plunker</a>
  <div class="runnable-example"
      path="examples/example-example97"
      module="formExample">

   
    <div class="runnable-example-file" 
      name="index.html"
      language="html"
      type="html">
      <pre><code>&lt;div ng-controller=&quot;ExampleController&quot;&gt;&#10;  &lt;form novalidate class=&quot;css-form&quot;&gt;&#10;    Name:&#10;      &lt;input type=&quot;text&quot; ng-model=&quot;user.name&quot; required /&gt;&lt;br /&gt;&#10;    E-mail: &lt;input type=&quot;email&quot; ng-model=&quot;user.email&quot; required /&gt;&lt;br /&gt;&#10;    Gender: &lt;input type=&quot;radio&quot; ng-model=&quot;user.gender&quot; value=&quot;male&quot; /&gt;male&#10;    &lt;input type=&quot;radio&quot; ng-model=&quot;user.gender&quot; value=&quot;female&quot; /&gt;female&lt;br /&gt;&#10;    &lt;button ng-click=&quot;reset()&quot;&gt;RESET&lt;/button&gt;&#10;    &lt;button ng-click=&quot;update(user)&quot;&gt;SAVE&lt;/button&gt;&#10;  &lt;/form&gt;&#10;&lt;/div&gt;&#10;&#10;&lt;style type=&quot;text/css&quot;&gt;&#10;  .css-form input.ng-invalid.ng-dirty {&#10;    background-color: #FA787E;&#10;  }&#10;&#10;  .css-form input.ng-valid.ng-dirty {&#10;    background-color: #78FA89;&#10;  }&#10;&lt;/style&gt;&#10;&#10;&lt;script&gt;&#10;  angular.module(&#39;formExample&#39;, [])&#10;    .controller(&#39;ExampleController&#39;, [&#39;$scope&#39;, function($scope) {&#10;      $scope.master = {};&#10;&#10;      $scope.update = function(user) {&#10;        $scope.master = angular.copy(user);&#10;      };&#10;&#10;      $scope.reset = function() {&#10;        $scope.user = angular.copy($scope.master);&#10;      };&#10;&#10;      $scope.reset();&#10;    }]);&#10;&lt;/script&gt;</code></pre>
    </div>
  

    <iframe class="runnable-example-frame" src="examples/example-example97/index.html" name="example-example97"></iframe>
  </div>
</div>

</p>
<h1 id="binding-to-form-and-control-state">Binding to form and control state</h1>
<p>A form is an instance of <a href="api/ng/type/form.FormController">FormController</a>.
The form instance can optionally be published into the scope using the <code>name</code> attribute.</p>
<p>Similarly, an input control that has the <a href="api/ng/directive/ngModel">ngModel</a> directive holds an
instance of <a href="api/ng/type/ngModel.NgModelController">NgModelController</a>.
Such a control instance can be published as a property of the form instance using the <code>name</code> attribute
on the input control.  The name attribute specifies the name of the property on the form instance.</p>
<p>This implies that the internal state of both the form and the control is available for binding in
the view using the standard binding primitives.</p>
<p>This allows us to extend the above example with these features:</p>
<ul>
<li>RESET button is enabled only if form has some changes</li>
<li>SAVE button is enabled only if form has some changes and is valid</li>
<li>custom error messages for <code>user.email</code> and <code>user.agree</code></li>
</ul>
<p>

<div>
  <a ng-click="openPlunkr('examples/example-example98')" class="btn pull-right">
    <i class="glyphicon glyphicon-edit">&nbsp;</i>
    Edit in Plunker</a>
  <div class="runnable-example"
      path="examples/example-example98"
      module="formExample">

   
    <div class="runnable-example-file" 
      name="index.html"
      language="html"
      type="html">
      <pre><code>&lt;div ng-controller=&quot;Controller&quot;&gt;&#10;  &lt;form name=&quot;form&quot; class=&quot;css-form&quot; novalidate&gt;&#10;    Name:&#10;      &lt;input type=&quot;text&quot; ng-model=&quot;user.name&quot; name=&quot;uName&quot; required /&gt;&lt;br /&gt;&#10;    E-mail:&#10;      &lt;input type=&quot;email&quot; ng-model=&quot;user.email&quot; name=&quot;uEmail&quot; required/&gt;&lt;br /&gt;&#10;    &lt;div ng-show=&quot;form.uEmail.$dirty &amp;&amp; form.uEmail.$invalid&quot;&gt;Invalid:&#10;      &lt;span ng-show=&quot;form.uEmail.$error.required&quot;&gt;Tell us your email.&lt;/span&gt;&#10;      &lt;span ng-show=&quot;form.uEmail.$error.email&quot;&gt;This is not a valid email.&lt;/span&gt;&#10;    &lt;/div&gt;&#10;&#10;    Gender: &lt;input type=&quot;radio&quot; ng-model=&quot;user.gender&quot; value=&quot;male&quot; /&gt;male&#10;    &lt;input type=&quot;radio&quot; ng-model=&quot;user.gender&quot; value=&quot;female&quot; /&gt;female&lt;br /&gt;&#10;&#10;    &lt;input type=&quot;checkbox&quot; ng-model=&quot;user.agree&quot; name=&quot;userAgree&quot; required /&gt;&#10;    I agree: &lt;input ng-show=&quot;user.agree&quot; type=&quot;text&quot; ng-model=&quot;user.agreeSign&quot;&#10;              required /&gt;&lt;br /&gt;&#10;    &lt;div ng-show=&quot;!user.agree || !user.agreeSign&quot;&gt;Please agree and sign.&lt;/div&gt;&#10;&#10;    &lt;button ng-click=&quot;reset()&quot; ng-disabled=&quot;isUnchanged(user)&quot;&gt;RESET&lt;/button&gt;&#10;    &lt;button ng-click=&quot;update(user)&quot;&#10;            ng-disabled=&quot;form.$invalid || isUnchanged(user)&quot;&gt;SAVE&lt;/button&gt;&#10;  &lt;/form&gt;&#10;&lt;/div&gt;</code></pre>
    </div>
  
    <div class="runnable-example-file" 
      name="script.js"
      language="js"
      type="js">
      <pre><code>angular.module(&#39;formExample&#39;, [])&#10;  .controller(&#39;ExampleController&#39;, [&#39;$scope&#39;, function($scope) {&#10;    $scope.master = {};&#10;&#10;    $scope.update = function(user) {&#10;      $scope.master = angular.copy(user);&#10;    };&#10;&#10;    $scope.reset = function() {&#10;      $scope.user = angular.copy($scope.master);&#10;    };&#10;&#10;    $scope.isUnchanged = function(user) {&#10;      return angular.equals(user, $scope.master);&#10;    };&#10;&#10;    $scope.reset();&#10;  }]);</code></pre>
    </div>
  

    <iframe class="runnable-example-frame" src="examples/example-example98/index.html" name="example-example98"></iframe>
  </div>
</div>

</p>
<h1 id="custom-validation">Custom Validation</h1>
<p>Angular provides basic implementation for most common html5 <a href="api/ng/directive/input">input</a>
types: (<a href="api/ng/input/input[text]">text</a>, <a href="api/ng/input/input[number]">number</a>, <a href="api/ng/input/input[url]">url</a>, <a href="api/ng/input/input[email]">email</a>, <a href="api/ng/input/input[radio]">radio</a>, <a href="api/ng/input/input[checkbox]">checkbox</a>), as well as some directives for validation (<code>required</code>, <code>pattern</code>, <code>minlength</code>, <code>maxlength</code>, <code>min</code>, <code>max</code>).</p>
<p>Defining your own validator can be done by defining your own directive which adds a custom validation function to the <code>ngModel</code> <a href="api/ng/type/ngModel.NgModelController">controller</a>.
To get a hold of the controller the directive specifies a dependency as shown in the example below.
The validation can occur in two places:</p>
<ul>
<li><p><strong>Model to View update</strong> -
Whenever the bound model changes, all functions in <a href="api/ng/type/ngModel.NgModelController#properties_$formatters">NgModelController#$formatters</a> array are pipe-lined, so that each of these functions has an opportunity to format the value and change validity state of the form control through <a href="api/ng/method/$setValidity">NgModelController#$setValidity</a>.</p>
</li>
<li><p><strong>View to Model update</strong> -
In a similar way, whenever a user interacts with a control it calls <a href="api/ng/method/$setViewValue">NgModelController#$setViewValue</a>.
This in turn pipelines all functions in the <a href="api/ng/type/ngModel.NgModelController#properties_$parsers">NgModelController#$parsers</a> array, so that each of these functions has an opportunity to convert the value and change validity state of the form control through <a href="api/ng/method/$setValidity">NgModelController#$setValidity</a>.</p>
</li>
</ul>
<p>In the following example we create two directives.</p>
<ul>
<li><p>The first one is <code>integer</code> and it validates whether the input is a valid integer.
For example <code>1.23</code> is an invalid value, since it contains a fraction.
Note that we unshift the array instead of pushing.
This is because we want to be first parser and consume the control string value, as we need to execute the validation function before a conversion to number occurs.</p>
</li>
<li><p>The second directive is a <code>smart-float</code>.
It parses both <code>1.2</code> and <code>1,2</code> into a valid float number <code>1.2</code>.
Note that we can&#39;t use input type <code>number</code> here as HTML5 browsers would not allow the user to type what it would consider an invalid number such as <code>1,2</code>.</p>
</li>
</ul>
<p>

<div>
  <a ng-click="openPlunkr('examples/example-example99')" class="btn pull-right">
    <i class="glyphicon glyphicon-edit">&nbsp;</i>
    Edit in Plunker</a>
  <div class="runnable-example"
      path="examples/example-example99"
      module="form-example1">

   
    <div class="runnable-example-file" 
      name="index.html"
      language="html"
      type="html">
      <pre><code>&lt;form name=&quot;form&quot; class=&quot;css-form&quot; novalidate&gt;&#10;  &lt;div&gt;&#10;    Size (integer 0 - 10):&#10;    &lt;input type=&quot;number&quot; ng-model=&quot;size&quot; name=&quot;size&quot;&#10;           min=&quot;0&quot; max=&quot;10&quot; integer /&gt;{{size}}&lt;br /&gt;&#10;    &lt;span ng-show=&quot;form.size.$error.integer&quot;&gt;This is not valid integer!&lt;/span&gt;&#10;    &lt;span ng-show=&quot;form.size.$error.min || form.size.$error.max&quot;&gt;&#10;      The value must be in range 0 to 10!&lt;/span&gt;&#10;  &lt;/div&gt;&#10;&#10;  &lt;div&gt;&#10;    Length (float):&#10;    &lt;input type=&quot;text&quot; ng-model=&quot;length&quot; name=&quot;length&quot; smart-float /&gt;&#10;    {{length}}&lt;br /&gt;&#10;    &lt;span ng-show=&quot;form.length.$error.float&quot;&gt;&#10;      This is not a valid float number!&lt;/span&gt;&#10;  &lt;/div&gt;&#10;&lt;/form&gt;</code></pre>
    </div>
  
    <div class="runnable-example-file" 
      name="script.js"
      language="js"
      type="js">
      <pre><code>var app = angular.module(&#39;form-example1&#39;, []);&#10;&#10;var INTEGER_REGEXP = /^\-?\d+$/;&#10;app.directive(&#39;integer&#39;, function() {&#10;  return {&#10;    require: &#39;ngModel&#39;,&#10;    link: function(scope, elm, attrs, ctrl) {&#10;      ctrl.$parsers.unshift(function(viewValue) {&#10;        if (INTEGER_REGEXP.test(viewValue)) {&#10;          // it is valid&#10;          ctrl.$setValidity(&#39;integer&#39;, true);&#10;          return viewValue;&#10;        } else {&#10;          // it is invalid, return undefined (no model update)&#10;          ctrl.$setValidity(&#39;integer&#39;, false);&#10;          return undefined;&#10;        }&#10;      });&#10;    }&#10;  };&#10;});&#10;&#10;var FLOAT_REGEXP = /^\-?\d+((\.|\,)\d+)?$/;&#10;app.directive(&#39;smartFloat&#39;, function() {&#10;  return {&#10;    require: &#39;ngModel&#39;,&#10;    link: function(scope, elm, attrs, ctrl) {&#10;      ctrl.$parsers.unshift(function(viewValue) {&#10;        if (FLOAT_REGEXP.test(viewValue)) {&#10;          ctrl.$setValidity(&#39;float&#39;, true);&#10;          return parseFloat(viewValue.replace(&#39;,&#39;, &#39;.&#39;));&#10;        } else {&#10;          ctrl.$setValidity(&#39;float&#39;, false);&#10;          return undefined;&#10;        }&#10;      });&#10;    }&#10;  };&#10;});</code></pre>
    </div>
  

    <iframe class="runnable-example-frame" src="examples/example-example99/index.html" name="example-example99"></iframe>
  </div>
</div>

</p>
<h1 id="implementing-custom-form-controls-using-ngmodel-">Implementing custom form controls (using <code>ngModel</code>)</h1>
<p>Angular implements all of the basic HTML form controls (<a href="api/ng/directive/input">input</a>, <a href="api/ng/directive/select">select</a>, <a href="api/ng/directive/textarea">textarea</a>), which should be sufficient for most cases.
However, if you need more flexibility, you can write your own form control as a directive.</p>
<p>In order for custom control to work with <code>ngModel</code> and to achieve two-way data-binding it needs to:</p>
<ul>
<li>implement <code>$render</code> method, which is responsible for rendering the data after it passed the <a href="api/ng.directive:ngModel.NgModelController#properties_$formatters">NgModelController#$formatters</a>,</li>
<li>call <code>$setViewValue</code> method, whenever the user interacts with the control and model needs to be updated. This is usually done inside a DOM Event listener.</li>
</ul>
<p>See <a href="guide/directive">$compileProvider.directive</a> for more info.</p>
<p>The following example shows how to add two-way data-binding to contentEditable elements.</p>
<p>

<div>
  <a ng-click="openPlunkr('examples/example-example100')" class="btn pull-right">
    <i class="glyphicon glyphicon-edit">&nbsp;</i>
    Edit in Plunker</a>
  <div class="runnable-example"
      path="examples/example-example100"
      module="form-example2">

   
    <div class="runnable-example-file" 
      name="index.html"
      language="html"
      type="html">
      <pre><code>&lt;div contentEditable=&quot;true&quot; ng-model=&quot;content&quot; title=&quot;Click to edit&quot;&gt;Some&lt;/div&gt;&#10;&lt;pre&gt;model = {{content}}&lt;/pre&gt;&#10;&#10;&lt;style type=&quot;text/css&quot;&gt;&#10;  div[contentEditable] {&#10;    cursor: pointer;&#10;    background-color: #D0D0D0;&#10;  }&#10;&lt;/style&gt;</code></pre>
    </div>
  
    <div class="runnable-example-file" 
      name="script.js"
      language="js"
      type="js">
      <pre><code>angular.module(&#39;form-example2&#39;, []).directive(&#39;contenteditable&#39;, function() {&#10;  return {&#10;    require: &#39;ngModel&#39;,&#10;    link: function(scope, elm, attrs, ctrl) {&#10;      // view -&gt; model&#10;      elm.on(&#39;blur&#39;, function() {&#10;        scope.$apply(function() {&#10;          ctrl.$setViewValue(elm.html());&#10;        });&#10;      });&#10;&#10;      // model -&gt; view&#10;      ctrl.$render = function() {&#10;        elm.html(ctrl.$viewValue);&#10;      };&#10;&#10;      // load init value from DOM&#10;      ctrl.$setViewValue(elm.html());&#10;    }&#10;  };&#10;});</code></pre>
    </div>
  

    <iframe class="runnable-example-frame" src="examples/example-example100/index.html" name="example-example100"></iframe>
  </div>
</div>

</p>


